home *** CD-ROM | disk | FTP | other *** search
/ JCSM Shareware Collection 1993 November / JCSM Shareware Collection - 1993-11.iso / cl720 / clpas33j.lzh / PCL4P.USR < prev    next >
Text File  |  1992-08-01  |  60KB  |  1,621 lines
  1.  
  2.  
  3.                           Personal Communications Library
  4.  
  5.                                 For Turbo Pascal
  6.  
  7.  
  8.                                     (PCL4P)
  9.  
  10.  
  11.  
  12.                                  USERS MANUAL
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                   Version 3.3
  19.  
  20.                                   Aug 3, 1992
  21.  
  22.  
  23.  
  24.  
  25.                         This software is provided as-is.
  26.                  There are no warranties, expressed or implied.
  27.  
  28.  
  29.  
  30.  
  31.                               Copyright (C) 1992
  32.                               All rights reserved
  33.  
  34.  
  35.  
  36.                               MarshallSoft Computing, Inc.
  37.                               Post Office Box 4543
  38.                               Huntsville AL 35815
  39.  
  40.                               Voice 205-881-4630
  41.                               FAX   205-881-4630
  42.                               BBS   205-880-9748
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.         PCL4P Users Manual                                     Page 1
  61.                               C O N T E N T S
  62.  
  63.  
  64.  
  65.  
  66.  
  67.          Chapter                                                   Page
  68.  
  69.          1.0 Introduction................................................3
  70.              1.1 User Support............................................4
  71.              1.2 A Typical Application...................................5
  72.              1.3 Installation............................................6
  73.          2.0 Library Organization........................................7
  74.              2.1 Initialization & Termination............................7
  75.              2.2 Configuration...........................................7
  76.              2.3 Modem Control & Status..................................8
  77.              2.4 Serial I/O..............................................8
  78.              2.5 Error Detection.........................................9
  79.              2.6 General Support.........................................9
  80.          3.0 Library Overview...........................................10
  81.              3.1 Using the Library......................................10
  82.              3.2 Example Programs.......................................10
  83.              3.3 Compiling & Linking....................................11
  84.          4.0 Talking to Your Modem......................................12
  85.              4.1 Modem Standards........................................12
  86.              4.2 Flow Control...........................................13
  87.              4.3 Modem Initialization...................................14
  88.          5.0 Problems...................................................15
  89.          6.0 Serial Communications......................................16
  90.              6.1 Communications Basics..................................16
  91.              6.2 Standard Port Addresses................................17
  92.              6.3 RS232 Signals..........................................18
  93.              6.4 National INS8250, INS16450, and INS16550 UARTs.........19
  94.              6.5 Register Summary.......................................20
  95.          7.0 Terminal Emulator Program (TERM)...........................22
  96.          8.0 Legal Issues...............................................23
  97.              8.1 Registration...........................................23
  98.              8.2 License................................................23
  99.              8.3 Warranty...............................................24
  100.          9.0 Summary....................................................25
  101.              9.1 Revision History.......................................25
  102.              9.2 Function Summary.......................................26
  103.              9.3 Further Reading........................................26
  104.         10.0 Other MarshallSoft Computing products......................27
  105.              10.1 The Personal Communications Library for C.............27
  106.              10.2 The Personal Protocol Library for C...................27
  107.              10.3 The Personal Protocol Library for Pascal..............27
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.         PCL4P Users Manual                                     Page 2
  121.          1.0 Introduction
  122.  
  123.  
  124.          The Personal Communications Library for Turbo Pascal (PCL4P) is an
  125.          asynchronous  communications  library  designed  for   experienced
  126.          software  developers  programming in Turbo Pascal, version 4.0 and
  127.          up. The PCL features:
  128.  
  129.          o 28 communications and support functions.
  130.          o Support for the high performance INS16550 UART.
  131.          o Supports hardware (RTS/CTS) flow control.
  132.          o Interrupt driven receiver.
  133.          o Supports 300 baud to 115,200 baud.
  134.          o Supports COM1, COM2, COM3, and  COM4.
  135.          o Adjustable receive queues from 8 bytes to 32 KB.
  136.          o Control-BREAK error exit.
  137.          o 17 communications error conditions trapped.
  138.          o Allows 2 ports to run concurrently.
  139.          o Complete modem control & status.
  140.          o Written in assembly language for small size & high speed.
  141.          o Terminal program featuring XMODEM, YMODEM, & YMODEM-G.
  142.  
  143.          Why should you buy PCL4P ? I can give you several good reasons.
  144.  
  145.            COMPLETE - PCL4P is complete since it provides absolute control
  146.                       of the serial ports (including the high  performance
  147.                       INS16550).
  148.  
  149.             COMPACT - PCL4P  is  very compact  at  less  than  6  KB. Your
  150.                       application doesn't carry a lot of excess code.
  151.  
  152.                FAST - PCL4P is fast since it will  run  at  38400  baud  on
  153.                       even  slow  8088 PCs (4.77 MHZ) and at 115200 baud on
  154.                       most everything else.
  155.  
  156.             SUPPORT - If you get stuck,  you talk  to  the programmer  that
  157.                       wrote the code, not a  person  hired  to  answer  the
  158.                       phone.
  159.  
  160.                 BBS - A BBS is  available  (2400  baud  N81)  in  order  to
  161.                       provide immediate support as necessary.
  162.  
  163.          NEWSLETTER - One  year  subscription  to  the  MSC  newsletter
  164.                       discusses communications  problems  and  solutions
  165.                       (published quarterly).
  166.  
  167.               PRICE - You get PCL4P for a very reasonable price !
  168.  
  169.            UPGRADES - Once you buy PCL4P, you can always update to  the  most
  170.                       recent  version  for  little  more  than  the  cost  of
  171.                       sending it out to you.
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.         PCL4P Users Manual                                     Page 3
  181.          1.1 User Support
  182.  
  183.          We want you to be successful in developing your applications using
  184.          PCL4P!  We depend on our customers to let us know what  they  need
  185.          in  a  communications  library.   This  means  we are committed to
  186.          providing the best communications library that we can. If you have
  187.          any suggestions or comments, please let us know.
  188.  
  189.          If you are having a problem using PCL4P, call us  at  205-881-4630
  190.          between  5  PM  and 9 PM CST Monday through Saturday, or FAX us at
  191.          the same telephone number at any time (24 hours).   You  can  also
  192.          call at other times and leave a message, and call back later for a
  193.          reply.
  194.  
  195.          You  may  also  call our User Support BBS (2400 baud, no parity, 8
  196.          data bits, 1  stop  bit)  at  205-880-9748  and  leave  a  message
  197.          (address it to the SYSOP).  We will usually have a reply ready for
  198.          you within 24 hours.
  199.  
  200.          The  BBS  is available 24 hours per day except at 2 PM Sundays for
  201.          maintenanace. All files are in standard ZIP format. The  BBS  will
  202.          contain  the latest shareware version of all MarshallSoft products
  203.          as well as related files such as:
  204.  
  205.              BUGS.ZIP  --  Bug report.
  206.              NEWS.ZIP  --  Latest news regarding our products.
  207.  
  208.          The  MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is
  209.          published quarterly.  It discusses various communications problems
  210.          and   solutions  using  PCL4P  as  well  as  related  information.
  211.          Registered users receive a  one  year  complimentary  subscription
  212.          when first registering and for each update purchased.
  213.  
  214.          Of  course, you can always write to us. You should receive a reply
  215.          within a week or so.
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.         PCL4P Users Manual                                     Page 4
  241.          1.2 A Typical Application
  242.  
  243.  
  244.          In  general,  there  are  two  classes  of applications that use a
  245.          communications library like PCL4P -- those that  use  a  modem  to
  246.          connect  to the outside world and those that connect directly to a
  247.          peripheral device. In either case, a typical  application  program
  248.          using PCL4P might look like the following code outline:
  249.  
  250.  
  251.  
  252.          ******************************************************************
  253.          *                                                                *
  254.          * program YourProgram                                            *
  255.          *                                                                *
  256.          * uses PCL4P;                                                    *
  257.          * ...                                                            *
  258.          * ...                                                            *
  259.          * var Buffer : array[0..1023] of Char;                           *
  260.          * ...                                                            *
  261.          * begin (* YourProgram *)                                        *
  262.          *    RetCode := SioRxBuf(Port,Ofs(Buffer),Seg(Buffer),Size1024); *
  263.          *    RetCode := SioParms(Port,NoParity,OneStopBit,WordLength8);  *
  264.          *    RetCode := SioReset(Port,Baud2400);                         *
  265.          *    ...                                                         *
  266.          *    ... ( application code )                                    *
  267.          *    ...                                                         *
  268.          *    RetCode := SioDone(Port);                                   *
  269.          * end. (* YourProgram *)                                         *
  270.          ******************************************************************
  271.  
  272.  
  273.          In the above example, SioRxBuf is called to set up the a 1024 byte
  274.          receive  buffer; SioParms is called to set up the parity, stop bit
  275.          count, and word length; SioReset is called to set the baud rate to
  276.          2400 and  reset  the  UART  (  Univeral  Asynchronous  Receiver  /
  277.          Transmitter ).
  278.  
  279.          Before  leaving your application, SioDone is called to restore the
  280.          prior state of the serial communications system.
  281.  
  282.          If  you  are  using  a  modem, you also need to be concerned about
  283.          initializing your modem correctly and handling any  required  flow
  284.          control. Refer to the "Talking to Your Modem" chapter for detailed
  285.          information.
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.         PCL4P Users Manual                                     Page 5
  301.          1.3 Installation
  302.  
  303.  
  304.          (1) Before installation of PCL4P , your compiler should already be
  305.          installed  on your system and tested. If you are not familiar with
  306.          makefiles,  refer  to  your  compiler  manual.  Examine  the  file
  307.          "FILES.LST" for a list of all the distribution files.
  308.  
  309.          (2) Make a backup  copy  of  your  distribution  disk.   Put  your
  310.          original distribution disk in a safe place.
  311.  
  312.          (3)  Create  a  work  directory  on your work disk ( normally your
  313.          harddisk ). For example, to create a work directory  named  PCL4P,
  314.          we first log onto the work disk and then type:
  315.  
  316.                                MKDIR PCL4P
  317.  
  318.          (4)  Copy  all the files from your backup copy of the distribution
  319.          disk to your work directory.  For example, to  copy  from  the  A:
  320.          drive to your work directory, we type:
  321.  
  322.                               CD PCL4P
  323.                               COPY A:*.*
  324.  
  325.          (5) Compile SIMPLE.PAS:
  326.  
  327.                               TPC SIMPLE
  328.  
  329.          SIMPLE.PAS should compile without any problems.
  330.  
  331.          (7) The recommended way to  test  SIMPLE  is  to  run  it  on  two
  332.          computers  connected  by a null modem cable.  Whatever is typed on
  333.          one computer should be displayed on the other.
  334.  
  335.          (8) Compile and run TERM.PAS.
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.         PCL4P Users Manual                                     Page 6
  361.          2.0 Library Organization
  362.  
  363.  
  364.          The  PCL4P  library is organized into six categories of functions.
  365.          Refer to the PCL  Reference  Manual  (PCL4P.REF)  for  details  on
  366.          individual functions.
  367.  
  368.  
  369.          2.1 Initialization & Termination
  370.  
  371.  
  372.          There are seven functions in the  initialization  and  termination
  373.          category.   Together,  SioParms,  SioFIFO,  SioRxBuf, and SioReset
  374.          initialize your serial communications  system.   Your  application
  375.          must  call  SioParms  and  SioRxBuf  before  calling SioReset, and
  376.          SioReset must be called before any serial I/O  processing  can  be
  377.          done.
  378.  
  379.          After initialization, SioParms and SioBaud can be called again  to
  380.          change  the communications parameters without resetting the serial
  381.          port. SioFlow can be called to enable hardware flow control.
  382.  
  383.          Before exiting from your  application,  SioDone  must  be  called.
  384.          Failure to call SioDone can crash your system later.
  385.  
  386.          SioRxBuf   -- Sets up receive buffer.
  387.          SioFIFO    -- Sets the interrupt level for the INS16550.
  388.          SioParms   -- Sets parity, stop bits, and word length.
  389.          SioReset   -- Initialize a serial port for processing.
  390.          SioDone    -- Terminates further serial processing.
  391.          SioBaud    -- Sets the baud rate of the selected port.
  392.          SioFlow    -- Enables / disables flow control.
  393.  
  394.  
  395.          2.2 Configuration
  396.  
  397.  
  398.          There  are two functions in the configuration category. SioUART is
  399.          used to change the UART base address for a communications port  at
  400.          a   non-standard  address,  while  SioIRQ  is  used  to  assign  a
  401.          nonstandard  IRQ  line  to  a  port.    (See   the   chapter   IBM
  402.          Communications  Ports  for more details on standard UART addresses
  403.          and IRQ lines).
  404.  
  405.          The  configuration  category  functions  should  be  called before
  406.          calling SioReset in order to have any effect.  There is no  "error
  407.          checking" done, so be very careful in using these functions.
  408.  
  409.          SioUART -- Sets the UART base address.
  410.          SioIRQ  -- Assigns an IRQ line to a port.
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.         PCL4P Users Manual                                     Page 7
  421.          2.3 Modem Control & Status
  422.  
  423.  
  424.          There  are  seven  functions  in  the  modem  control  and  status
  425.          category which provide your application with complete control over
  426.          the status and control bits of your modem.
  427.  
  428.          There are two modem control bits, "Data Terminal Ready" (DTR)  and
  429.          "Request  To  Send" (RTS). These bits can be read, set, or cleared
  430.          by SioDTR and SioRTS.
  431.  
  432.          There are four modem status bits, "Data Set Ready"  (DSR),  "Clear
  433.          To  Send"  (CTS), "Ring Indicator" (RI), and "Data Carrier Detect"
  434.          (DCD). SioModem can read any of the  modem  status  bits.  SioDSR,
  435.          SioCTS,  SioRI,  and  SioDCD  can only read their respective modem
  436.          status bit.
  437.  
  438.          Refer to the chapter entitled "RS232 Signals" for a discussion  of
  439.          each of the control and status bits.
  440.  
  441.          SioDTR    -- Set, clear, or read the Data Terminal Ready (DTR) bit.
  442.          SioRTS    -- Sets, clears, or reads the Request to Send (RTS) line.
  443.          SioModem  -- Reads the modem status register.
  444.          SioDSR    -- Reads the Data Set Ready (DSR) modem status bit.
  445.          SioCTS    -- Reads the Clear to Send (CTS) modem status bit
  446.          SioDCD    -- Reads the Data Carrier Detect (DCD) modem status bit.
  447.          SioRI     -- Reads the Ring Indicator (RI) modem status bit.
  448.  
  449.  
  450.          2.4 Serial I/O
  451.  
  452.  
  453.          There are six  library  functions  in  the  serial  I/O  category.
  454.          Together,  these  functions  give  the programmer complete control
  455.          over serial I/O.  Higher level functions  such  as  protocols  and
  456.          smart  modem communications can be completely implemented in terms
  457.          of these functions. Refer to the example code.
  458.  
  459.          SioGetc  and SioPutc perform all the actual serial I/O.  SioUnGetc
  460.          and SioRxFlush modify the receive queue. SioLine can  be  used  to
  461.          test for UART errors.
  462.  
  463.          SioGetc    -- Reads the next character from the serial line.
  464.          SioPutc    -- Transmit a character over a serial line.
  465.          SioUnGetc  -- "Un-gets" (puts back) a specified character.
  466.          SioRxFlush -- Flush (clears) the receive buffer.
  467.          SioRxQue   -- Returns the number of characters in the receive queue.
  468.          SioLine    -- Reads the line status register.
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.         PCL4P Users Manual                                     Page 8
  481.          2.5  Error Detection
  482.  
  483.  
  484.          There are four functions in the error detection category. They are
  485.          concerned with detecting or reporting communications errors.   Use
  486.          of  these  functions  can make your application significantly more
  487.          robust.
  488.  
  489.          SioBrkKey   can   be   used  as  an  "emergency"  exit  from  your
  490.          application. SioBrkSig can read or modify the UART break bit. This
  491.          is useful for signalling the remote system that a fatal  condition
  492.          has  occurred.  SioLoopBack  can  be used to test the integrity of
  493.          your UART.  SioError displays a error message corresponding to  an
  494.          error  code  returned  from a PCL4P function.
  495.  
  496.          SioBrkKey -- Returns non-zero if the Control-BREAK key was pressed
  497.          SioBrkSig -- Asserts, cancels, or detects  BREAK  signal.
  498.          SioError  -- Displays  error  in  text.
  499.          SioLoopBack -- Performs a UART loopback test.
  500.  
  501.  
  502.          2.6 General Support
  503.  
  504.  
  505.          There are two functions in the general support category.  Strictly
  506.          speaking,  they are not communications functions, but they take up
  507.          a very small amount of additional memory.   Registered  users  can
  508.          remove these functions from the library if needed.
  509.  
  510.          SioInfo     -- Returns the library version & memory model.
  511.          SioTimer    -- Returns the number of system clock tics.
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.         PCL4P Users Manual                                     Page 9
  541.          3.0 Library Organization
  542.  
  543.          3.1 Using the Library
  544.  
  545.  
  546.          The  PCL4P  library has been tested on a TANDY 1000 (4.77 MHZ 8088
  547.          IBM PC clone), a TANDY 3000 (80286 IBM AT clone), a  TANDY  1400LT
  548.          (IBM XT clone), and a Gateway 2000 Cache (25 MHZ 80386-DX).  PCL4P
  549.          has been tested under MSDOS 2.11, 3.2, 3.3, 4.01, and 5.0.
  550.  
  551.          Please  examine  the  PCL4P.PAS file. Note that COM1 is defined as
  552.          port zero, not port one.  The user must assume  the  responsibilty
  553.          for  passing the correct information when calling PCL4P functions.
  554.  
  555.  
  556.          3.2 Example Programs
  557.  
  558.  
  559.          Two communications programs are provided as a demonstration of the
  560.          PCL4P library -- SIMPLE and TERM.
  561.  
  562.          SIMPLE  is  provided  as  the  simpliest example of communications
  563.          programming  using  PCL4P.   The  user  should  compile  and  link
  564.          SIMPLE.PAS as a test of the library.
  565.  
  566.          If you have two computers, connect them together with a null modem
  567.          cable and run SIMPLE on both machines.  The baud rate in SIMPLE is
  568.          hard  coded to 2400 baud. It is easily changed in the source code.
  569.          Start SIMPLE by typing SIMPLE followed by the port. For example:
  570.  
  571.               SIMPLE 1
  572.  
  573.          Once SIMPLE is started on both computers, whatever is typed on one
  574.          machine should be displayed on the other, and vice versa.
  575.  
  576.          The  TERM program is a more capable terminal emulator than SIMPLE.
  577.          It features modem initialization, hardware flow control, and  file
  578.          transfer   using   XMODEM,  YMODEM,  and  YMODEM-G  communications
  579.          protocols.  TERM can be used to call up any bulletin board system,
  580.          including the MarshallSoft Computing BBS.  Start  TERM  by  typing
  581.          TERM followed by the port and baud rate. For example:
  582.  
  583.               TERM 4 2400
  584.  
  585.          Refer to the chapter "Terminal Emulator Program"  for  a  complete
  586.          discussion of TERM.
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.         PCL4P Users Manual                                     Page 10
  601.          3.3 Compiling and Linking
  602.  
  603.  
  604.          Registered users may wish to assemble  PCL4PLIB.ASM.  To  assemble
  605.          using the Microsoft assembler:
  606.  
  607.                MASM PCL4PLIB /DPASCAL_MODEL;
  608.  
  609.          To build the library TPU:
  610.  
  611.                TPC PCL4P
  612.  
  613.          To compile the sample programs:
  614.  
  615.                TPC SIMPLE.PAS
  616.  
  617.                TPC TERM.PAS /m
  618.  
  619.          A  makefile (  TERM.MAK  )  is  also  provided  for  the  TERM.PAS
  620.          program. To compile TERM and all dependent units, type:
  621.  
  622.                MAKE -FTERM
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.         PCL4P Users Manual                                     Page 11
  661.          4.0 Talking to Your Modem
  662.  
  663.  
  664.          A modem is  used  to  extend  the  distance  over  which  you  may
  665.          communicate.   Without  a  modem, your RS232 cable is limited to a
  666.          maximum of approximately 50  feet.  But  with  a  modem,  you  can
  667.          communicate literally around the world.
  668.  
  669.  
  670.          4.1 Modem Standards
  671.  
  672.  
  673.          Two modems can communicate over a telephone line only if they  are
  674.          both  using  the  same signaling frequencies and modulation, which
  675.          are determined by the the modem standards used.   Modem  standards
  676.          can  be  divided  into three sets: (1) speed, (2) data compression
  677.          used, and (3) error control.
  678.  
  679.          The Bell standards (103 & 212A) are those of AT&T.  The CCITT (The
  680.          International  Consultative Committee for Telephone and Telegraph)
  681.          standards are designated as "V. ".
  682.  
  683.  
  684.          Speed
  685.  
  686.          Bell 103  --   300 baud
  687.          Bell 212A --  1200 baud
  688.          V.21      --   300 baud
  689.          V.22bis   --  1200 & 2400 baud
  690.          V.32      --  4800 & 9600 baud
  691.          V.32bis   --  4800, 7200, 9600, 12000, and 14400 baud
  692.  
  693.  
  694.          Data Compression
  695.  
  696.          MNP 5     --  Microcom Networking Protocol (proprietary).
  697.          V.42bis   --  International data compression standard.
  698.  
  699.  
  700.          Error Control
  701.  
  702.          MNP 2,3,4 --  Three level error correction (public domain).
  703.          V.42      --  International error correction standard.
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.         PCL4P Users Manual                                     Page 12
  721.          4.2 Flow Control
  722.  
  723.  
  724.          With modems using data compression, the modem to modem  connection
  725.          will  run  at various speeds depending on the quality of the line.
  726.          The computer to modem connection will be at  a  fixed  baud  rate.
  727.          Therefore,  a  protocol (flow control) is necessary to synchronize
  728.          the data flow  between  and  modems  and  the  computer  to  modem
  729.          connection.   Refer  to  your modem manual for information on flow
  730.          control protocols supported.
  731.  
  732.          Two  flow  control  protocols  are  used  by most all modems which
  733.          require flow control. Software flow control is  called  "XON/XOFF"
  734.          (other  software  flow  control  character  pairs  are defined but
  735.          operate the same as XON/XOFF) and hardware flow control is  called
  736.          "RTS/CTS".  Most modems which require flow control enable hardware
  737.          flow control by default.
  738.  
  739.          In   XON/XOFF  (software)  flow  control,  the  computer  suspends
  740.          transmitting data if it receives a XOFF character  (13  hex)  from
  741.          the  modem,  and  continues  transmitting  when  it receives a XON
  742.          character (11 hex).  Similiarly, the computer can signal the modem
  743.          not to send any more data by transmitting a XOFF to  it,  and  can
  744.          tell the modem to continue transmission be sending a XON.
  745.  
  746.          In  RTS/CTS  (hardware)  flow control, the RTS line is used by the
  747.          computer to signal the modem , while the CTS line is used  by  the
  748.          modem  to  signal  the  computer.  The  RTS line is set OFF by the
  749.          computer to tell the modem to suspend transmission, and set to  ON
  750.          to  tell  the modem to continue transmission.  The CTS line is set
  751.          to OFF by the modem to tell the computer to stop transmitting, and
  752.          set to ON to tell the computer to continue transmitting.
  753.  
  754.          Given  the  choice,  always  choose  hardware  flow  control  over
  755.          software   flow   control   so   that  all  data  transmission  is
  756.          transparent.  If hardware flow control is not the  default  (which
  757.          it almost always is), your should modify your modem initialization
  758.          string to turn hardware flow control on.
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.         PCL4P Users Manual                                     Page 13
  781.          4.3 Modem Initialization
  782.  
  783.  
  784.          If your application uses a modem (as opposed to using a null modem
  785.          cable),  then  you  should always send an initialization string to
  786.          your modem if it is a programmable modem such  as  those  made  by
  787.          Hayes.   Communication  programs  such as PROCOMM and TELIX always
  788.          send such a string automatically as soon as they start up.
  789.  
  790.          The particular initialization string depends on the make  of  your
  791.          modem.   For Hayes and Hayes AT command set compatible modems, the
  792.          following string (followed by a carriage return) should work:
  793.  
  794.               AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
  795.  
  796.          Refer to your Modem User's Guide for a full  discussion  of  these
  797.          commands. A brief description is as follows:
  798.  
  799.          AT     Modem attention command.
  800.          E1     Modem will echo what you send to it.
  801.          S7=60  Wait 60 seconds for carrier and/or dial tone.
  802.          S11=60 Use 60 milliseconds for tone dialing duration & spacing.
  803.          V1     Display result code as words (not numbers).
  804.          X1     Use the extended result message (CONNECT XXXX) set.
  805.          Q0     Modem returns result codes.
  806.          S0=0   Do not answer RING.
  807.  
  808.          If your application will answer incoming calls, then  set  the  S0
  809.          register to the ring on which to automatically answer.
  810.  
  811.          If you send the above codes by using SioPutc (as opposed to typing
  812.          them from the keyboard), then follow these guidelines:
  813.  
  814.          (1) Send an initial  carriage  return  before  the  initialization
  815.          string.
  816.  
  817.          (2) Pause at least two tics (18 tics to  the  second)  after  each
  818.          character  sent  as  your  modem needs the time to perform its own
  819.          internal processing.  Pause a little longer if your modem  is  not
  820.          accepting your initialization string.
  821.  
  822.          (3) Pause one and a half seconds after sending any  initialization
  823.          command  such  as ATZ or AT&F since your modem must do quite a bit
  824.          of processing.
  825.  
  826.          If you experience any problems in initializing your  Hayes  modem,
  827.          you should first reset it to factory settings by sending:
  828.  
  829.               AT&F
  830.  
  831.          Refer  to  the  TERM  program (functions SendTo and WaitFor in the
  832.          file MODEM_IO.PAS) for an example  of  sending  an  initialization
  833.          string to a Hayes compatible modem.
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.         PCL4P Users Manual                                     Page 14
  841.          5.0 Problems
  842.  
  843.  
  844.          If  you cannot get your application to run properly, first compile
  845.          and run the  terminal  emulator  program  TERM  provided  on  your
  846.          distribution  disk.   If  you  are  using  a null modem cable or a
  847.          non-programmable modem, be sure not to  define  AT_COMMAND_SET  in
  848.          DEFINES.PAS.  If  you  are using a Hayes compatible modem, then do
  849.          define AT_COMMAND_SET {$DEFINE AT_COMMAND_SET}. If you  are  using
  850.          a  programmable modem which is not Hayes compatible, then you must
  851.          modify the initialization string for your particular modem.
  852.  
  853.          If your application does not run but TERM runs correctly, then you
  854.          have  most  likely made a programming mistake in your application.
  855.          MarshallSoft Computing cannot debug your  application,  especially
  856.          over  the telephone!  However, consider each of the following when
  857.          searching for an error in your application.
  858.  
  859.          1.  Did you include the "uses PCL4P" statement ?
  860.  
  861.          2.  Is your receive buffer large enough ? If you are using 1K data
  862.              blocks in YMODEM, then your receive buffer should be at  least
  863.              1K ( 2K if baud rates above 38400 are to be used ).
  864.  
  865.          4.  Have you selected too high a baud rate ( if you  are  using  a
  866.              slow PC ) ?  If only one COM port is being run, you should  be
  867.              able to run at 38400 baud on 8088 machines and 115200 on  most
  868.              286 and all 386 and 486 machines.
  869.  
  870.          5.  Are  you  attempting  to  run  another  application   in   the
  871.              background ?  Try running  without any other programs  running
  872.              in the background ( unload all TSR programs ).
  873.  
  874.          6.  If you are running two COM ports simultaneously, are you using
  875.              separate receive buffers ? ( you should ).
  876.  
  877.          7.  Did SioReset return a zero value ?  If not, then you must call
  878.              SioReset again. See TERM.PAS for an example.
  879.  
  880.          8.  Did you send the proper initialization string to your modem ?
  881.              Did you set DTR and RTS ? ( you should ).
  882.  
  883.          9.  Do you have more than one COM1 port, etc.  For example, if you
  884.              have a COM1 port on your motherboard,  you cannot add  another
  885.              COM1  port  or  modem  board  that  uses  COM1  without  first
  886.              disabling the COM1 on the motherboard.
  887.  
  888.          Registered  users  can call (205) 881 - 4630 from 5 PM to 9 PM CST
  889.          Monday through Friday for help.
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.         PCL4P Users Manual                                     Page 15
  901.          6.0 Serial Communications
  902.  
  903.          6.1 Communications Basics
  904.  
  905.  
  906.          The  heart  of  serial  communications  is  the  UART   (Universal
  907.          Asynchronous   Receiver   Transmitter).    The  IBM  PC/XT/AT  and
  908.          compatibles use the INS8250, INS16450, or the INS16550 UART.   The
  909.          purpose of the UART is:
  910.  
  911.          (1)  To convert bytes from the CPU (Central Processing Unit), into
  912.          a serial format by adding the necessary start,  stop,  and  parity
  913.          bits  to  each byte before transmission, and to then transmit each
  914.          bit at the correct baud rate.
  915.  
  916.          (2) To convert the incoming stream (at a specified baud  rate)  of
  917.          serial  bits  into  bytes  by removing the start, stop, and parity
  918.          bits before being made available to the CPU.
  919.  
  920.          The  UART  is  part of the serial interface circuitry which allows
  921.          the CPU to send and receive signals over the RS232 lines. This can
  922.          be diagrammed as follows:
  923.  
  924.                                Serial Interface
  925.                             *********************
  926.                             *                   *
  927.          *******  Data Bus  *     ********      *    RS232 Signals
  928.          * CPU **************     * UART *      ******************
  929.          *******            *     ********      *
  930.                             *                   *
  931.                             *********************
  932.  
  933.          The  INS8250/16450/16550  UART  is  capable of operating in one of
  934.          two  modes,  "polled"  and   "interrupt   driven".    The   serial
  935.          communications  functions  in the BIOS uses the polled method.  In
  936.          this approach, the CPU is typically in  a  loop  asking  the  UART
  937.          over  and  over  again  if  it  has a byte ready. If its does, the
  938.          polling code returns the byte.  But, if the  next  byte  comes  in
  939.          before  the  polling  code  is  executing again, then that byte is
  940.          lost.
  941.  
  942.          In  the  interrupt  driven  approach  (used  by PCL4P for incoming
  943.          data), when a byte is received by the UART, an "Interrupt  Service
  944.          Routine"  (ISR)  is  executed  immediately, suspending temporarily
  945.          whatever else is executing.  The ISR then  moves  the  byte  to  a
  946.          buffer  so  that your application program can later read it. Refer
  947.          to the sections entitled "RS232  Signals"  and  "National  INS8250
  948.          UART" for further information on these topics.
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.         PCL4P Users Manual                                     Page 16
  961.          6.2 Standard Port Addresses
  962.  
  963.  
  964.          There  are  a  few  things to know about how serial communications
  965.          ports are used by  IBM  PC/XT/AT  and  compatible  computers.  The
  966.          standard IBM PC/XT/AT configuration values are as follows:
  967.  
  968.          Port     Reg Base   IRQ Line   Vector
  969.          COM1        3F8H        4        12
  970.          COM2        2F8H        3        11
  971.          COM3        3E8H        4        12
  972.          COM4        2E8H        3        11
  973.  
  974.          PCL4P assumes the  above  values.  If  necessary,  the  UART  base
  975.          address    can   be  changed  by  SioUART,  and  IRQ  lines can be
  976.          re-assigned by SioIRQ. Refer to the  PCL4P  Reference  Manual  for
  977.          specific details.
  978.  
  979.          When installing new communications cards, the following guidelines
  980.          are recommended:
  981.  
  982.          (1) Be sure to read the documentation  for  the  hardware  you  are
  983.          installing.   Pay special attention to UART base addresses and IRQ
  984.          lines.
  985.  
  986.          (2) If you have a choice in base addresses and IRQ  lines,  always
  987.          choose standard values as defined above.
  988.  
  989.          (3) The first port should be COM1, the second COM2, etc.
  990.  
  991.          (4)  Use  SioUART  to  zero  all  unused ports (for example, call
  992.          SioUART(COM4,0) if there is no COM4 port installed).
  993.  
  994.          (5)  Be  carefull not to configure two ports for the same address.
  995.          This is easier to do than you may believe.
  996.  
  997.          (6) Choose an external modem over an internal  one.   It  is  much
  998.          easier  to  debug problems with an external modem than an internal
  999.          one.
  1000.  
  1001.          (7)  Select  hardware  flow  control  (RTS/CTS) if flow control is
  1002.          required and hardware flow control is not the default.
  1003.  
  1004.          (8) Always test your port as soon as it is installed.
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.         PCL4P Users Manual                                     Page 17
  1021.          6.3 RS-232 Signals
  1022.  
  1023.  
  1024.          RS-232 is the name of the serial data interface standard  used  to
  1025.          connect  computers  to  modems.  Most IBM compatible computers are
  1026.          built with at least one serial port and use either DB9 (9 pin)  or
  1027.          DB25 (25 pin) connectors.
  1028.  
  1029.          A summary of these pins and  their  function  follows.   For  more
  1030.          detailed  information, refer to one of the many books dealing with
  1031.          RS-232 interfacing.
  1032.  
  1033.          Signal Ground Pin 7 (DB25), Pin 5 (DB9)
  1034.  
  1035.          The SG line is used as the common signal ground, and  must  always
  1036.          be connected.
  1037.  
  1038.          Transmit Data Pin 2 (DB25), Pin 3 (DB9)
  1039.  
  1040.          The TX line is used to carry data from the computer to the modem.
  1041.  
  1042.          Receive Data Pin 3 (DB25), Pin 2 (DB9)
  1043.  
  1044.          The RX line is used to carry data from the modem to the computer.
  1045.  
  1046.          Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
  1047.  
  1048.          The  DTR  line is used by the computer to signal the modem that it
  1049.          is ready. DTR should be set high when talking to a modem.
  1050.  
  1051.          Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
  1052.  
  1053.          The DSR line is used by the modem to signal the computer  that  it
  1054.          is ready.
  1055.  
  1056.          Request to Send Pin 4 (DB25), Pin 7 (DB9)
  1057.  
  1058.          The  RTS  line  is  used  to "turn the line around" in half duplex
  1059.          modems, and for hardware flow control in most modems that  require
  1060.          flow control.
  1061.  
  1062.          Clear to Send Pin 5 (DB25), Pin 8 (DB9)
  1063.  
  1064.          The  CTS  line  is  used  to "turn the line around" in half duplex
  1065.          modems, and for hardware flow control in most modems that  require
  1066.          flow control.
  1067.  
  1068.          Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
  1069.  
  1070.          The DCD line is used by the modem to signal the  computer  that  a
  1071.          data carrier signal is present.
  1072.  
  1073.          Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
  1074.  
  1075.          The RI line is asserted when a 'ring' occurs.
  1076.  
  1077.  
  1078.  
  1079.  
  1080.         PCL4P Users Manual                                     Page 18
  1081.          6.4 National INS8250, INS16450, and INS16550 UARTs
  1082.  
  1083.  
  1084.          The  Personal  Communications  Library  is  based  on the standard
  1085.          National INS8250, INS16450, and INS16550 UARTs. The 8250  was  the
  1086.          original  UART  used  in the IBM PC, whereas the 16450 is a faster
  1087.          version found on most 286 & up machines. The 16550 contains  a  16
  1088.          byte  FIFO  to further reduce communications overhead. These UARTs
  1089.          consists of 8 register ports as follows:
  1090.  
  1091.          Offset    R/W   Register
  1092.            0       R/W   Receiver (read) / Transmitter (write)
  1093.            1       R/W   Interrupt Enable (read)
  1094.            2       R     Interrupt Identification
  1095.            2       W     FIFO control (INS16550 only)
  1096.            3       R/W   Data Format (Line Control)
  1097.            4       R/W   RS-232 (Modem) Control
  1098.            5       R/W   Line Status
  1099.            6       R/W   RS-232 (Modem) Status
  1100.            7       R/W   Not used.
  1101.  
  1102.          The  UART  registers  are  based  at  3F8  (COM1), 2F8 (COM2), 3E8
  1103.          (COM3), and 2E8 (COM4). COM1 and COM3 share  interrupt  vector  12
  1104.          and  interrupt  request  line  IRQ4  while  COM2  and  COM4  share
  1105.          interrupt vector 11 and interrupt request line IRQ3.   This  means
  1106.          that  COM1  and  COM3  cannot  both  be  used  at  the  same time.
  1107.          Similarly, COM2 and COM4 cannot both be used at the same time.
  1108.  
  1109.  
  1110.          Port     Reg Base   IRQ Line   Vector
  1111.          COM1        3F8H        4        12
  1112.          COM2        2F8H        3        11
  1113.          COM3        3E8H        4        12
  1114.          COM4        2E8H        3        11
  1115.  
  1116.          Four sources of interrupts are possible with the 8250  and  16550:
  1117.          (1) receiver error or BREAK, (2) receiver data ready, (3) ready to
  1118.          transmit,  and  (4) RS232 input.  These four sources of interrupts
  1119.          are summarized as follows:
  1120.  
  1121.          Source of Interrupt        Action Required to Clear
  1122.          Receiver error or BREAK.   Read Line Status register.
  1123.          Receiver data.             Read data from data register.
  1124.          Transmitter Buffer Empty.  Write to data register or read IID reg.
  1125.          RS232 input.               Read Modem Status register.
  1126.  
  1127.          However,  PCL4P  only  enables  the receiving data interrupt. This
  1128.          means that interrupts can only be caused by incoming data.
  1129.  
  1130.          If  you  are not familiar with the INS8250, several good books are
  1131.          available.   Refer  to  the  Serial  Communications  chapter   for
  1132.          recommendations.    Although  a  knowledge  of  the  8250  is  not
  1133.          necessary to use PCL4P, a  general  knowledge  of  the  theory  of
  1134.          asynchronous serial communications is recommended.
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.         PCL4P Users Manual                                     Page 19
  1141.          6.5 Register Summary
  1142.  
  1143.  
  1144.          REG 0 : Data Register
  1145.  
  1146.          Reading  from  the data register fetches the next input byte, once
  1147.          it is ready.  Writing to the  data  register  transmits  the  byte
  1148.          written to it over the serial line.
  1149.  
  1150.          REG 1 : Interrupt Enable 
  1151.  
  1152.          The  Interrupt  Enable  register  enables  each  of  four types of
  1153.          interrupts when the appropriate bit is set to a one.
  1154.  
  1155.          bit 3 : Enable interrupt on RS232 input.
  1156.          bit 2 : Enable interrupt on receiver error or break.
  1157.          bit 1 : Enable interrupt on transmitter buffer empty (TBE).
  1158.          bit 0 : Enable interrupt on received data (RxRDY).
  1159.  
  1160.          REG 2 : Interrupt Identification (IID)
  1161.  
  1162.          Reading  the  Interrupt Identification (read only) register once
  1163.          an interrupt has occurred identifies the interrupt as follows:
  1164.  
  1165.          Bit 2  Bit 1  Bit 0  Priority    Interrupt
  1166.            0      0      1      none      none
  1167.            1      1      0      0 (high)  Serialization or break.
  1168.            1      0      0      1         Received data.
  1169.            0      1      0      2         Transmitter Buffer Empty.
  1170.            0      0      0      3 (low)   RS232 Input.
  1171.  
  1172.          In the INS16650, REG 2 (write  only)  is  also  the  FIFO  control
  1173.          register.   Writing  bits  6  &  7 will set the FIFO trigger level
  1174.          (number of bytes received before an interrupt is generated).
  1175.  
  1176.          Bit 7  Bit 6   Trigger             Bit 7  Bit 6   Trigger
  1177.           0      0      1 byte               1      1      8 bytes
  1178.           0      1      4 bytes              1      1      14 bytes
  1179.  
  1180.          REG 3 : Line Control
  1181.  
  1182.          RS232 line parameters are selected by writing to this register.
  1183.  
  1184.          bit 7 : DLAB = 0
  1185.          bit 6 : BREAK on(1), off(0).
  1186.          bits 5-3: Parity None(000),ODD(001),EVEN(011),MARK(101),SPACE(111)
  1187.          bit 2 : One stop bit(0), two stop bits(1).
  1188.          bits 1-0: Data bits = 5 (00), 6(01), 7(10), 8(11).
  1189.  
  1190.          When the Divisor Latch Access Bit (DLAB) is 1, registers 0  and  1
  1191.          become the LS and MS bytes of the Baud Rate Divisor registers.
  1192.  
  1193.          Baud   Divisor      Baud  Divisor      Baud  Divisor
  1194.           300    0180        4800   0018       38400   0003
  1195.          1200    0060        9600   000C       57600   0002
  1196.          2400    0030       19200   0006      115200   0001
  1197.  
  1198.  
  1199.  
  1200.         PCL4P Users Manual                                     Page 20
  1201.          REG 4 : Modem Control
  1202.  
  1203.          RTS, DTR, loopback testing, and General Purpose Outputs #1 and  #2
  1204.          are controlled by the Modem Control register as follows:
  1205.  
  1206.          bit 4 : Enable local loopback.
  1207.          bit 3 : Enable GP02. Necessary for 8250 interrupts.
  1208.          bit 2 : Enable GP01.
  1209.          bit 1 : Set / clear RTS.
  1210.          bit 0 : Set / clear DTR.
  1211.  
  1212.          REG 5 : Line Status
  1213.  
  1214.          Reading  the  Line  Status register provides status information as
  1215.          follows (1 for TRUE, 0 for FALSE) :
  1216.  
  1217.          bit 6 : Transmitter Empty.
  1218.          bit 5 : Transmitter Buffer Empty (TBE).
  1219.          bit 4 : BREAK detect.
  1220.          bit 3 : Framing error.
  1221.          bit 2 : Parity error.
  1222.          bit 1 : Overrun error.
  1223.          bit 0 : Data Ready.
  1224.  
  1225.          REG 6 : Modem Status
  1226.  
  1227.          Reading the Modem Status register provides  the  following  status
  1228.          information (1 for TRUE, 0 for FALSE) :
  1229.  
  1230.          bit 7 : DCD status.
  1231.          bit 6 : RI status.
  1232.          bit 5 : DSR status.
  1233.          bit 4 : CTS status.
  1234.          bit 3 : Delta DCD status.
  1235.          bit 2 : Delta RI status.
  1236.          bit 1 : Delta DSR status.
  1237.          bit 0 : Delta CTS status.
  1238.  
  1239.          The delta bits (bits 0 through 3) are  set  whenever  one  of  the
  1240.          status  bits  (bits 4 through 7) changes (from 0 to 1 or from 1 to
  1241.          0) since the last time that the Modem Status  register  was  read.
  1242.          Reading the Modem Status register clear the delta bits.
  1243.  
  1244.          REG 7 : Scratch Register
  1245.  
  1246.          There is no function associated with  register  7.   It  does  not
  1247.          exist in early versions of the 8250.
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.         PCL4P Users Manual                                     Page 21
  1261.          7.0 Terminal Emulator Example Program
  1262.  
  1263.  
  1264.          TERM is an communications program suitable for calling up bulletin
  1265.          board  systems  (BBS)  and  performing  as  a  PC  to PC file copy
  1266.          program.  TERM itself is not part of the  communications  library,
  1267.          but  rather  it  is  provided  as  an  example of a communications
  1268.          application using PCL4P.
  1269.  
  1270.          TERM can send a standard Hayes standard AT command set  string  to
  1271.          your  modem.   An  initialization  string is sent by TERM provided
  1272.          that AT_COMMAND_SET is defined in DEFINES.PAS.
  1273.  
  1274.             {$DEFINE AT_COMMAND_SET}
  1275.  
  1276.          Refer to the chapter "Modem Initialization" for  a  discussion  of
  1277.          initialization strings.
  1278.  
  1279.          TERM  also supports hardware flow control (RTS/CTS). Hardware flow
  1280.          control is observed provided that the constant RTS_CTS_CONTROL  is
  1281.          defined in the file DEFINES.PAS.
  1282.  
  1283.             {$DEFINE RTS_CTS_CONTROL}
  1284.  
  1285.          Refer to the chapter "Flow Control" for a discussion  of  hardware
  1286.          flow control.
  1287.  
  1288.          TERM  can  also  exchange  files  using  XMODEM,   YMODEM   (batch
  1289.          capability),  and  YMODEM-G  (streaming  YMODEM  used  with  error
  1290.          correcting modems)  communications  protocols.   TERM  can  accept
  1291.          wildcards in the filename so that multiple files can be sent using
  1292.          YMODEM  and  YMODEM-G.   The  protocol timing can also be adjusted
  1293.          (this  should  not  be  necessary)  by  modifying  the   constants
  1294.          SHORT_WAIT and LONG_WAIT in the PCL4P.PAS file.
  1295.  
  1296.          TERM  can also be used as a PC to PC transfer program using a null
  1297.          modem cable. In  this  case,  AT_COMMAND_SET  and  RTS_CTS_CONTROL
  1298.          should not be defined in the file DEFINES.PAS:
  1299.  
  1300.          Be  advised  that  most  null modem cables are do NOT swap RTS and
  1301.          CTS, which is necessary for hardware flow control. This means that
  1302.          RTS_CTS_CONTROL should never be defined when using  a  null  modem
  1303.          cable unless you are absolutely sure that RTS and CTS are swapped.
  1304.  
  1305.          To start TERM, type TERM followed by the port (1  to  4)  and  the
  1306.          baud  rate (300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600,
  1307.          or 115200). For example, to start TERM at 2400 baud on port COM4:
  1308.  
  1309.             TERM 4 2400
  1310.  
  1311.          The TERM program (but of course not the library itself) is  placed
  1312.          in  the  public domain by MarshallSoft Computing, Inc., and can be
  1313.          used in any way desired by the user.
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.         PCL4P Users Manual                                     Page 22
  1321.          8.0 Legal Issues
  1322.  
  1323.          8.1 Registration
  1324.  
  1325.  
  1326.          The shareware version of PCL4P.LIB is provided  so  that  you  may
  1327.          personally  determine  the usefulness of the product for yourself.
  1328.          If you can use  the  Personal  Communications  Library  for  Turbo
  1329.          Pascal  ,  please  register your use with us. Send $45 plus $3 S&H
  1330.          ($6 outside of North America) to:
  1331.  
  1332.                   MarshallSoft Computing, Inc.
  1333.                   Post Office Box  4543
  1334.                   Huntsville AL 35815
  1335.  
  1336.          Please pay by check in US dollars drawn on a  US  bank.   Purchase
  1337.          Orders (POs) are accepted from recognized US schools and companies
  1338.          listed  in  Dunn  &  Bradstreet.   Print  the file PCL4P.INV if an
  1339.          invoice is needed. The registered package is mailed first class US
  1340.          Mail (packet air mail overseas). If you are  in  a  hurry,  please
  1341.          call  us and we can ship immediately within the USA by COD (street
  1342.          address and phone number required).
  1343.  
  1344.          The registered package includes:
  1345.  
  1346.          o  Assembler source code for the library.
  1347.          o  Printed Users Manual.
  1348.          o  Printed Reference Manual.
  1349.          o  Telephone, FAX, BBS support for one year.
  1350.          o  One year subscription (quarterly) to MSC newsletter.
  1351.          o  All updates (with printed manuals) are $15  plus  $3  S&H
  1352.             ($6 outside of North America).
  1353.  
  1354.          PCL4P.ASM is the source code for the library. The source  code  is
  1355.          copyrighted  by MarshallSoft Computing, Inc. The user is granted a
  1356.          license to use the PCL4P object code in his own application  only.
  1357.          PCL4P.ASM  is  not  shareware and may not be sold or given away to
  1358.          anyone.
  1359.  
  1360.          The registered user will receive the latest version  of  PCL4P  by
  1361.          return  mail.  A 5.25" diskette is provided unless a 3.5" diskette
  1362.          is requested.
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.         PCL4P Users Manual                                     Page 23
  1381.  
  1382.          8.2 License
  1383.  
  1384.  
  1385.  
  1386.          MarshallSoft  Computing,  Inc. grants the registered user of PCL4P
  1387.          the right to use one copy of the PCL4P library (in object form) on
  1388.          a single computer in  the  development  of  any  software  product
  1389.          without  any  royalties.  The user may not use the library on more
  1390.          than one computer at the same  time.   The  source  code  for  the
  1391.          library (PCL4P.ASM) may not be released in whole or in part.
  1392.  
  1393.  
  1394.          8.3 Warranty
  1395.  
  1396.  
  1397.          MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING  TO
  1398.          THIS  SOFTWARE,  WHETHER  EXPRESSED  OR IMPLIED, INCLUDING BUT NOT
  1399.          LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY  AND  FITNESS
  1400.          FOR  A  PARTICULAR  PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY
  1401.          AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING,  INC.
  1402.          NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION,
  1403.          OR  DELIVERY  OF  THIS  SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
  1404.  
  1405.          CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT  OF  THE  USE  OR
  1406.          INABILITY  TO  USE  SUCH  SOFTWARE EVEN IF MARSHALLSOFT COMPUTING,
  1407.          INC.  HAS BEEN ADVISED OF  THE  POSSIBILITY  OF  SUCH  DAMAGES  OR
  1408.          CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY
  1409.          FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO
  1410.          USE  THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON
  1411.          USING  THE  SOFTWARE  BEARS  ALL  RISK  AS  TO  THE  QUALITY   AND
  1412.          PERFORMANCE OF THE SOFTWARE.
  1413.  
  1414.          Some  states  do not allow the exclusion of the limit of liability
  1415.          for consequential or incidental damages, so the  above  limitation
  1416.          may not apply to you.
  1417.  
  1418.          This  agreement  shall  be  governed  by  the laws of the State of
  1419.          Alabama and shall inure to the benefit of Marshallsoft  Computing,
  1420.          Inc.   and  any successors, administrators, heirs and assigns. Any
  1421.          action or proceeding brought by either  party  against  the  other
  1422.          arising  out of or related to this agreement shall be brought only
  1423.          in a STATE or FEDERAL COURT of competent jurisdiction  located  in
  1424.          Madison County, Alabama. The parties hereby consent to in personam
  1425.          jurisdiction of said courts.
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.         PCL4P Users Manual                                     Page 24
  1441.          9.0 Summary
  1442.  
  1443.          9.1 Revision History
  1444.  
  1445.  
  1446.          Version 1.0 -- 14 January 1991 -- original release.
  1447.  
  1448.          Version 1.1 -- 11 March 1991
  1449.  
  1450.          o  Added SioUnGetc() function to library.
  1451.  
  1452.          Version 1.2 -- 1 June 1991
  1453.  
  1454.          o  Name changed to Personal Communications Library.
  1455.          o  Minor bug fixes.
  1456.  
  1457.          Version 1.3 -- 1 July 1991
  1458.  
  1459.          o  Added NORESET option to SioReset.
  1460.          o  Added SioDSR, SioCTS, SioDCD, and SioRI.
  1461.          o  Added SioLoopBack function to library.
  1462.          o  Added LOOPBACK.PAS example program.
  1463.  
  1464.          Version 2.0 -- 1 Nov 1991
  1465.  
  1466.          o  All example code released in shareware package.
  1467.          o  Fixed bug due to Microsoft Assembler (MASM 5.0,5.1) error.
  1468.  
  1469.          Version 3.0 -- 15 Jan 1991
  1470.  
  1471.          o  Added XMODEM & YMODEM to example code.
  1472.          o  Added SioUART function.
  1473.          o  Added "UART undefined" error code.
  1474.          o  Added "Bad or missing UART" error code.
  1475.          o  Added "Port already enabled" error code.
  1476.          o  Added "Cannot enable both COM1 & COM3 ..." error code.
  1477.          o  Fixed several minor bugs ( using new automated testing ).
  1478.  
  1479.          Version 3.1 -- 1 March 1992
  1480.  
  1481.          o  Added SioFIFO ( INS16550 only ).
  1482.          o  Added SioIRQ function.
  1483.          o  Increased maximum receive buffer size to 32K bytes.
  1484.  
  1485.          Version 3.2 -- 1 May 1992
  1486.  
  1487.          o  Modified SioReset so that it no longer clears DTR & RTS.
  1488.          o  Modified SioModel & renamed to SioInfo.
  1489.          o  Fixed bug in SioDone when using 2 ports simultaneously.
  1490.          o  Added SioFlow to library.
  1491.          o  Added YMODEM-G protocol to TERM program.
  1492.  
  1493.          Version 3.3 -- 3 August 1992
  1494.  
  1495.          o  Fixed bug in SioUnGet when using 2 ports simultaneously.
  1496.          o  Add SioRead function.
  1497.  
  1498.  
  1499.  
  1500.         PCL4P Users Manual                                     Page 25
  1501.          9.2 Function Summary
  1502.  
  1503.  
  1504.          Refer to the  PCL4P  Reference  Manual  (PCL4P.REF)  for  detailed
  1505.          information  on  the  communications  and support functions. A one
  1506.          line summary of each function follows:
  1507.  
  1508.  
  1509.          SioBaud     Sets the baud rate of the selected port.
  1510.          SioBrkKey   Returns non-zero if the Control-BREAK key was pressed.
  1511.          SioBrkSig   Asserts, cancels, or detects BREAK signal.
  1512.          SioCTS      Reads the Clear to Send (CTS) modem status bit.
  1513.          SioDCD      Reads the Data Carrier Detect (DCD) modem status bit.
  1514.          SioDone     Terminates further serial processing.
  1515.          SioDSR      Reads the Data Set Ready (DSR) modem status bit.
  1516.          SioDTR      Set, clear, or read the Data Terminal Ready (DTR) bit.
  1517.          SioError    Displays error in text.
  1518.          SioFIFO     Sets the interrupt level for the INS16550.
  1519.          SioFlow     Enables / disables hardware flow control.
  1520.          SioGetc     Reads the next character from the serial line.
  1521.          SioInfo     Returns library version number.
  1522.          SioIRQ      Assigns an IRQ line to a port.
  1523.          SioLine     Reads the line status register.
  1524.          SioLoopBack Performs a UART loopback test.
  1525.          SioModem    Reads the modem status register.
  1526.          SioParms    Sets parity, stop bits, and word length.
  1527.          SioPutc     Transmit a character over a serial line.
  1528.          SioReset    Initialize a serial port for processing.
  1529.          SioRI       Reads the Ring Indicator (RI) modem status bit.
  1530.          SioRTS      Sets, clears, or reads the Request to Send (RTS) line.
  1531.          SioRxBuf    Sets up receive buffer.
  1532.          SioRxFlush  Flushes (clears) the receive buffer.
  1533.          SioRxQue    Returns the number of characters in the receive queue.
  1534.          SioTimer    Returns the number of system clock tics.
  1535.          SioUART     Sets the UART base address.
  1536.          SioUnGetc   "Un-gets" (puts back) a specified character.
  1537.  
  1538.  
  1539.          9.3 Further Reading
  1540.  
  1541.  
  1542.          The best way to learn about serial communications  is  to  read  a
  1543.          good  book  on the subject. Several good texts are available.  Two
  1544.          that I like are (sorry but most communications  books  use  C  for
  1545.          their examples) :
  1546.  
  1547.          (1) C Programmers's Guide to Serial Communications by Joe Campbell
  1548.          (SAMS)
  1549.  
  1550.          (2) Mastering Serial Communications by Peter Gofton (SYBEX).
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.         PCL4P Users Manual                                     Page 26
  1561.          10.0 Other MarshallSoft Computing Products
  1562.  
  1563.          10.1 The Personal Communications Library for C
  1564.  
  1565.          The Personal Communications Library for  Pascal  (PCL4C)  is  a  C
  1566.          language  version  of  the  Personal  Communications  Library  for
  1567.          Pascal, and is available for $45 plus $3 S&H ($6 S&H overseas). It
  1568.          contains   the   same   library   functions,   example   programs,
  1569.          documentation, and user support.
  1570.  
  1571.          10.2 The Personal Protocol Library for C
  1572.  
  1573.          The  Personal  Protocol  Library for C (PPL4C) consists of a state
  1574.          driven C language library  which  implements  XMODEM,  XMODEM-CRC,
  1575.          XMODEM-1K, XMODEM-G, YMODEM, and YMODEM-G file transfer protocols.
  1576.          This  allows  the  communications  application  to  run  two ports
  1577.          simultaneously while interacting with the user  at  the  keyboard.
  1578.          The  state  drive library functionally emulates background tasking
  1579.          with standard MSDOS.
  1580.  
  1581.          The primary application area for the protocol library  is  in  the
  1582.          development  of custom BBS programs (and programs that call BBS's)
  1583.          which  require  either  multiple  lines  or  which  require   user
  1584.          interaction  while  a  file transfer is underway. The state driven
  1585.          architecture can  also  be  used  as  a  framework  and  guide  to
  1586.          developing customized file transfer protocols.
  1587.  
  1588.          The protocol library (PPL4C) requires the C communications library
  1589.          PCL4C.   The  PPL4C  comes  with fully commented C source code, an
  1590.          example  program  which  can  transmit  or   receive   two   files
  1591.          simultaneously,  printed documentation, and one year of telephone,
  1592.          FAX, and BBS support.
  1593.  
  1594.          The Personal Protocol Library for C is available for $35  plus  $3
  1595.          S&H ($6 S&H overseas).  It can also be ordered together with the C
  1596.          communications  library  for  $65  for  both,  plus  $3.50 S&H ($7
  1597.          overseas).
  1598.  
  1599.          10.3 The Personal Protocol Library for Pascal
  1600.  
  1601.          The Personal Protocol Library for Pascal (PPL4P) is a Turbo Pascal
  1602.          version  of  the Personal Protocol Library for C, and is available
  1603.          for $35 plus $3 S&H ($6  S&H  overseas).   It  contains  the  same
  1604.          library  functions,  example  programs,  documentation,  and  user
  1605.          support.
  1606.  
  1607.          The Personal Protocol Library for Pascal is available for $35 plus
  1608.          $3  S&H  ($6  S&H overseas).  It can also be ordered together with
  1609.          the Pascal communications library for $65 for both, plus $3.50 S&H
  1610.          ($7 overseas).
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.         PCL4P Users Manual                                     Page 27
  1621.